ODSemanticInterface

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODSemanticInterface

Superclasses
ODExtension --> ODRefCntObject --> ODObject
Subclasses
none

An object of the ODSemanticInterface class implements an extension that handles semantic events for your part. It is recommended, but not required, that your part editor support this extension.

Description
When a document is opened, the session object creates a single semantic interface object for the document shell. All parts of that document share the document shell's semantic interface object; you can obtain a reference to it by calling the session object's AcquireShellSemtInterface method (page 605).
The methods defined by the ODSemanticInterface class parallel handlers and functions defined for Apple events in Inside Macintosh: Interapplication Communication. The following information assumes a basic knowledge of handling Apple events and resolving object specifiers.
The ODSemanticInterface class is designed to respond to semantic events received by your part. Because OpenDoc is responsible for dispatching semantic events to your part, many of the handlers that would normally be defined by multiple functions using the Apple Event Manager are grouped conceptually in the ODSemanticInterface class. For example, the CallEventHandler method (page 590) provides a bottleneck that all Apple events sent to your part must go through.
The methods of this class consist of four types: semantic-event handlers, object accessors, object-callback functions, and other handlers. OpenDoc calls the semantic-event handlers of your subclass to handle Apple events intended for your part. The object accessors and object-callback functions are used by OpenDoc to resolve object specifiers for your part. OpenDoc calls other handlers for special purposes. Your implementation of these methods can consist of separate handlers or a single large procedure that handles all of your part's semantic events.
The ODSemanticInterface class is an abstract superclass that you must subclass to create your semantic interface. OpenDoc accesses your semantic interface object by calling your part's AcquireExtension method (page 466), which returns a reference to the extension object. The semantic-interface extension type is identified by the constant kODExtSemanticInterface. If your part supports this extension, your part subclass must override the AcquireExtension, HasExtension, and ReleaseExtension methods and provide an appropriate implementation. For more information related to extension objects, see the ODExtension class description (page 212).
For more information about creating and sending Apple events to other parts, see the ODMessageInterface class description (page 411). For more information related to resolving object specifiers, see the ODNameResolver class description (page 419) and the "Resolving and Creating Object Specifier Records" chapter of Inside Macintosh: Interapplication Communication. For more information related to Apple event and coercion handlers, see the "Responding to Apple Events" chapter of Inside Macintosh: Interapplication Communication. For general information on scripting support in OpenDoc, see the chapter on semantic events and scripting in the OpenDoc Programmer's Guide for the MacOS.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODSemanticInterface.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODSemanticInterface, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this semantic interface object. The SOM library calls this method when this semantic interface object is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this semantic interface object's subclass-specific initialization method; see also the InitSemanticInterface method (page 598).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODSemanticInterface, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this semantic interface object, including any storage related to additional instance variables initialized in this semantic interface object. The SOM library calls this method when this semantic interface object is deleted; this method must not fail.

Release
The Release method decrements an object's reference count by 1; it is inherited from the ODRefCntObject class.
void Release ();
If you subclass ODSemanticInterface, you can override this method to release an object and reclaim valuable resources like memory. Your override method must call its inherited method at the beginning of your implementation.
The inherited Release method decrements this semantic interface object's reference count by 1. The inherited method may delete this semantic interface object from memory if this object's reference count becomes 0. A part editor calls this method when it no longer needs a reference to this semantic interface object.

Purge
The Purge method frees memory on request; it is inherited from the ODObject class.
ODSize Purge (in ODSize size);
Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. If you subclass ODSemanticInterface, you must override this method or risk running out of available memory. Your override method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.
Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods
This section presents summary descriptions of the ODSemanticInterface methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing

InitSemanticInterface
Initializes this semantic interface object.
Semantic-Event Handlers

CallEventHandler
Processes the specified Apple event object for the part.
Object Accessors

CallObjectAccessor
Resolves the object specifier into a target and returns a reference to an OpenDoc token identifying that target.
Object-Callback Functions

CallCountProc
Counts the number of elements of the specified type in the specified container.
CallCompareProc
Compares two descriptors.
CallGetMarkTokenProc
Gets the mark token to use for marking a large series of objects.
CallMarkProc
Marks a large series of objects using the specified mark token.
CallAdjustMarksProc
Unmarks a series of objects that were previously marked.
CallDisposeTokenProc
Deallocates any part-specific data structures stored in the specified token.
CallGetErrDescProc
Gets a reference to the part's global error descriptor object.
Other Handlers

CallCoercionHandler
Coerces the specified descriptor to a different type.
CallPredispatchProc
Calls the predispatch handler for this semantic interface's part.
UsingPredispatchProc
Specifies whether the predispatch method is currently being called whenever OpenDoc receives an Apple event.
OSL Settings

GetOSLSupportFlags
Returns the flags that indicate which handlers this semantic interface object supports.
SetOSLSupportFlags
Sets the flags that indicate which handlers this semantic interface object supports.

Methods
CallAdjustMarksProc
CallCoercionHandler
CallCompareProc
CallCountProc
CallDisposeTokenProc
CallEventHandler
CallGetErrDescProc
CallGetMarkTokenProc
CallMarkProc
CallObjectAccessor
CallPredispatchProc
GetOSLSupportFlags
InitSemanticInterface
SetOSLSupportFlags
UsingPredispatchProc